Kattava opas Python-pakettien jakeluun PyPI:n kautta, sisältäen versionhallinnan parhaat käytännöt, työkalut ja työnkulut kehittäjille maailmanlaajuisesti.
Python-pakettien jakelu: PyPI-julkaisu ja versionhallinta
Pythonin laaja ekosysteemi perustuu valtavaan pakettien kokoelmaan, joka on helposti saatavilla Python Package Indexin (PyPI) kautta. Tämä opas tarjoaa kattavan yleiskatsauksen siitä, kuinka voit jakaa omia Python-pakettejasi PyPI:n kautta varmistaen, että ne ovat kehittäjien saatavilla maailmanlaajuisesti. Käymme läpi olennaiset työkalut, versionhallinnan parhaat käytännöt sekä työnkulut laadukkaiden Python-pakettien luomiseen ja julkaisemiseen.
Miksi jakaa oma Python-paketti?
Python-paketin jakelu tarjoaa lukuisia etuja:
- Työsi jakaminen: Mahdollistaa muiden kehittäjien helpon koodisi uudelleenkäytön, edistäen yhteistyötä ja innovaatiota. Kuvittele maailmanlaajuinen tiimi käyttämässä sinun erikoistuneita Pythonilla rakennettuja data-analyysityökalujasi.
- Riippuvuuksien hallinta: Yksinkertaistaa riippuvuuksien hallintaa muissa projekteissa. Pakettisi voidaan asentaa yhdellä komennolla kaikkine riippuvuuksineen.
- Avoimen lähdekoodin edistäminen: Mahdollistaa osallistumisesi avoimen lähdekoodin yhteisöön ja tunnustuksen saamisen työstäsi. Monet kriittiset ohjelmistokomponentit ovat avoimen lähdekoodin paketteja, joita ylläpitävät kehittäjät maailmanlaajuisesti.
- Versionhallinta ja päivitykset: Tarjoaa jäsennellyn tavan hallita versioita, julkaista päivityksiä ja korjata virheitä. Tämä varmistaa, että käyttäjillä on aina pääsy pakettisi uusimpaan ja luotettavimpaan versioon.
- Helppo asennus: Yksinkertaistaa asennusta käyttäjille komennolla `pip install sinun-paketin-nimi`.
Olennaiset työkalut Python-pakettien jakeluun
Useat työkalut ovat välttämättömiä Python-pakettien luomisessa ja jakelussa:
- setuptools: Laajalti käytetty kirjasto paketin metatietojen, kuten nimen, version, riippuvuuksien ja sisääntulopisteiden (entry points), määrittelyyn. Se on de facto -standardi Python-projektien paketoinnissa.
- wheel: Jakelumuoto, joka tarjoaa tehokkaamman ja luotettavamman asennusprosessin lähdekoodijakeluihin verrattuna. Wheelit ovat esikäännettyjä jakeluita, jotka voidaan asentaa ilman kääntämistä.
- twine: Työkalu paketin turvalliseen lataamiseen PyPI:hin. Twine salaa tunnuksesi ja paketin datan siirron aikana, suojaten salakuuntelulta ja väliintulohyökkäyksiltä.
- venv/virtualenv: Nämä ovat työkaluja eristettyjen Python-ympäristöjen luomiseen. Virtuaaliympäristöjen käyttö on ratkaisevan tärkeää riippuvuuksien hallinnassa ja eri projektien välisten konfliktien välttämisessä.
Projektin pystyttäminen
Ennen kuin voit jakaa pakettisi, sinun on rakennettava projektisi oikein.
Esimerkki projektirakenteesta
my_package/ ├── my_package/ │ ├── __init__.py │ ├── module1.py │ └── module2.py ├── tests/ │ ├── __init__.py │ ├── test_module1.py │ └── test_module2.py ├── README.md ├── LICENSE ├── setup.py └── .gitignore
Selitys:
- my_package/: Pääkansio, joka sisältää pakettisi lähdekoodin.
- my_package/__init__.py: Tekee `my_package`-kansiosta Python-paketin. Se voi olla tyhjä tai sisältää alustuskoodia.
- my_package/module1.py, my_package/module2.py: Python-moduulisi, jotka sisältävät varsinaisen koodin.
- tests/: Kansio, joka sisältää yksikkötestisi. On ratkaisevan tärkeää kirjoittaa testejä pakettisi laadun ja luotettavuuden varmistamiseksi.
- README.md: Markdown-tiedosto, joka sisältää kuvauksen paketistasi, käyttöohjeet ja muuta oleellista tietoa. Tämä on usein ensimmäinen asia, jonka käyttäjät näkevät PyPI:ssä.
- LICENSE: Tiedosto, joka sisältää lisenssin, jolla pakettisi jaetaan (esim. MIT, Apache 2.0, GPL). Sopivan lisenssin valitseminen on olennaista määriteltäessä, miten muut voivat käyttää koodiasi.
- setup.py: Pääkonfiguraatiotiedosto, joka määrittelee pakettisi metatiedot ja käännösohjeet.
- .gitignore: Määrittää tiedostot ja kansiot, jotka Gitin tulisi jättää huomiotta (esim. väliaikaistiedostot, käännösartefaktit).
Tiedoston `setup.py` luominen
`setup.py`-tiedosto on pakettisi jakelun ydin. Se sisältää metatietoja paketistasi sekä ohjeet sen kääntämiseen ja asentamiseen. Tässä on esimerkki:
import setuptools
with open("README.md", "r") as fh:
long_description = fh.read()
setuptools.setup(
name="my_package", # Korvaa pakettisi nimellä
version="0.1.0",
author="Oma Nimi", # Korvaa nimelläsi
author_email="oma.sahkoposti@example.com", # Korvaa sähköpostillasi
description="Pieni esimerkkipaketti",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/omakayttaja/my_package", # Korvaa arkistosi URL-osoitteella
packages=setuptools.find_packages(),
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
python_requires='>=3.6',
install_requires=[
"requests", # Esimerkkiriippuvuus
],
)
Selitys:
- name: Pakettisi nimi, jota käytetään PyPI:ssä. Valitse yksilöllinen ja kuvaava nimi.
- version: Pakettisi versionumero. Noudata semanttista versiointia (katso alla).
- author, author_email: Nimesi ja sähköpostiosoitteesi.
- description: Lyhyt kuvaus paketistasi.
- long_description: Pidempi, yksityiskohtaisempi kuvaus, joka tyypillisesti luetaan `README.md`-tiedostostasi.
- long_description_content_type: Määrittää pitkän kuvauksesi muodon (esim. "text/markdown").
- url: Pakettisi kotisivun URL-osoite (esim. GitHub-arkisto).
- packages: Luettelo paketeista, jotka sisällytetään jakeluusi. `setuptools.find_packages()` löytää automaattisesti kaikki projektisi paketit.
- classifiers: Metatietoja, jotka auttavat käyttäjiä löytämään pakettisi PyPI:stä. Valitse sopivat luokittimet Trove Classifiers -luettelosta. Harkitse luokittimien lisäämistä tuetuille Python-versioille, käyttöjärjestelmille ja lisensseille.
- python_requires: Määrittää vähimmäis-Python-version, jota pakettisi käyttö edellyttää.
- install_requires: Luettelo riippuvuuksista, joita pakettisi vaatii. Nämä riippuvuudet asennetaan automaattisesti, kun pakettisi asennetaan.
Versionhallinta: Semanttinen versiointi
Semanttinen versiointi (SemVer) on laajalti omaksuttu versiointijärjestelmä, joka tarjoaa selkeän ja johdonmukaisen tavan viestiä pakettisi muutosten luonteesta.
SemVer-versionumero koostuu kolmesta osasta: `PÄÄ.SIVU.PAIKKAUS` (MAJOR.MINOR.PATCH).
- PÄÄ (MAJOR): Kasvatetaan, kun teet yhteensopimattomia API-muutoksia. Tämä osoittaa merkittävän muutoksen, joka saattaa vaatia käyttäjiä päivittämään koodinsa.
- SIVU (MINOR): Kasvatetaan, kun lisäät toiminnallisuutta taaksepäin yhteensopivalla tavalla. Tämä merkitsee uusia ominaisuuksia tai parannuksia, jotka eivät riko olemassa olevaa koodia.
- PAIKKAUS (PATCH): Kasvatetaan, kun teet taaksepäin yhteensopivia virheenkorjauksia. Tämä on tarkoitettu pienille korjauksille, jotka eivät lisää uusia ominaisuuksia tai riko olemassa olevaa toiminnallisuutta.
Esimerkkejä:
- 1.0.0: Ensimmäinen julkaisu.
- 1.1.0: Lisätty uusi ominaisuus rikkomatta olemassa olevaa koodia.
- 1.0.1: Korjattu virhe 1.0.0-julkaisussa.
- 2.0.0: Tehty yhteensopimattomia API-muutoksia.
SemVerin käyttö auttaa käyttäjiä ymmärtämään pakettisi uuteen versioon päivittämisen vaikutukset.
Paketin kääntäminen
Kun `setup.py`-tiedostosi on määritetty, voit kääntää pakettisi.
- Luo virtuaaliympäristö: On erittäin suositeltavaa luoda virtuaaliympäristö pakettisi riippuvuuksien eristämiseksi. Käytä `python3 -m venv .venv` (tai `virtualenv .venv`) ja aktivoi se sitten (`source .venv/bin/activate` Linuxilla/macOS:llä, `.venv\Scripts\activate` Windowsilla).
- Asenna kääntämisriippuvuudet: Suorita `pip install --upgrade setuptools wheel`.
- Käännä paketti: Suorita `python setup.py sdist bdist_wheel`. Tämä komento luo kaksi jakelutiedostoa `dist`-kansioon: lähdekoodijakelun (sdist) ja wheel-jakelun (bdist_wheel).
`sdist` sisältää lähdekoodisi ja `setup.py`-tiedoston. `bdist_wheel` on esikäännetty jakelu, joka voidaan asentaa nopeammin.
Paketin julkaiseminen PyPI:hin
Ennen kuin voit julkaista pakettisi, sinun on luotava tili PyPI:hin (https://pypi.org/) ja luotava API-avain. Tätä avainta käytetään lataustesi todentamiseen.
- Rekisteröidy PyPI:hin: Mene osoitteeseen https://pypi.org/account/register/ ja luo tili.
- Luo API-avain: Mene osoitteeseen https://pypi.org/manage/account/, vieritä alas "API tokens" -osioon ja luo uusi avain. Säilytä tämä avain turvallisesti, sillä tarvitset sitä pakettisi lataamiseen.
- Asenna Twine: Suorita `pip install twine`.
- Lataa pakettisi: Suorita `twine upload dist/*`. Sinulta kysytään käyttäjätunnusta (`__token__`) ja salasanaa (luomasi API-avain).
Tärkeä turvallisuushuomautus: Älä koskaan committaa API-avaintasi arkistoosi. Säilytä se turvallisesti ja käytä ympäristömuuttujia tai muita turvallisia menetelmiä sen käyttämiseen latausprosessin aikana.
Paketin asennuksen testaaminen
Paketin julkaisemisen jälkeen on olennaista testata, että se voidaan asentaa oikein.
- Luo uusi virtuaaliympäristö: Tämä varmistaa, että testaat asennusta puhtaassa ympäristössä.
- Asenna pakettisi: Suorita `pip install sinun-paketin-nimi`.
- Tuo ja käytä pakettiasi: Tuo pakettisi Python-tulkissa ja varmista, että se toimii odotetusti.
Jatkuva integraatio ja jatkuva käyttöönotto (CI/CD)
Automatisoidaksesi paketin kääntämis-, testaus- ja julkaisuprosessia voit käyttää CI/CD-työkaluja, kuten GitHub Actions, GitLab CI tai Travis CI.
Tässä on esimerkki GitHub Actions -työnkulusta, joka kääntää ja julkaisee pakettisi PyPI:hin:
name: Julkaise PyPI:hin
on:
release:
types: [published]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python 3.x
uses: actions/setup-python@v2
with:
python-version: 3.x
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install setuptools wheel twine
- name: Build package
run: python setup.py sdist bdist_wheel
- name: Publish package to PyPI
run: |
twine upload dist/* \
-u __token__ \
-p ${{ secrets.PYPI_API_TOKEN }}
Selitys:
- Tämä työnkulku käynnistyy, kun uusi julkaisu (release) julkaistaan GitHubissa.
- Se hakee koodin, asentaa Pythonin, asentaa riippuvuudet, kääntää paketin ja lataa sen PyPI:hin.
secrets.PYPI_API_TOKENon GitHub-salaisuus (secret), joka tallentaa PyPI API-avaimesi. Sinun on määritettävä tämä salaisuus GitHub-arkistosi asetuksissa.
Parhaat käytännöt Python-pakettien jakelussa
- Kirjoita kattava dokumentaatio: Sisällytä yksityiskohtainen `README.md`-tiedosto sekä API-dokumentaatio käyttämällä työkaluja kuten Sphinx. Selkeä ja täydellinen dokumentaatio on ratkaisevan tärkeää, jotta pakettisi on helppokäyttöinen.
- Kirjoita yksikkötestejä: Testaa koodisi perusteellisesti sen laadun ja luotettavuuden varmistamiseksi. Käytä testauskehystä, kuten pytest tai unittest.
- Noudata PEP 8 -tyyliohjeita: Noudata Python Enhancement Proposal 8 (PEP 8) -tyyliopasta varmistaaksesi yhtenäisen ja luettavan koodin.
- Käytä lisenssiä: Valitse sopiva avoimen lähdekoodin lisenssi määrittääksesi, miten muut voivat käyttää koodiasi.
- Pidä riippuvuutesi ajan tasalla: Päivitä säännöllisesti pakettisi riippuvuudet hyötyäksesi virheenkorjauksista, tietoturvakorjauksista ja uusista ominaisuuksista.
- Käytä virtuaaliympäristöä: Kehitä ja testaa pakettiasi aina virtuaaliympäristössä riippuvuuksien eristämiseksi.
- Harkitse kansainvälistämistä (i18n) ja lokalisointia (l10n): Jos pakettisi käsittelee käyttäjälle näkyvää tekstiä tai dataa, harkitse sen mukauttamista eri kielille ja alueille. Tämä laajentaa potentiaalista käyttäjäkuntaasi maailmanlaajuisesti. Työkalut, kuten Babel, voivat auttaa tässä.
- Käsittele eri aikavyöhykkeitä ja valuuttoja: Jos pakettisi käsittelee päivämääriä, aikoja tai rahansiirtoja, ota huomioon eri aikavyöhykkeet ja valuutat ympäri maailmaa. Käytä sopivia kirjastoja ja API-rajapintoja näiden monimutkaisuuksien oikeaan käsittelyyn.
- Tarjoa selkeitä virheilmoituksia: Kirjoita informatiivisia virheilmoituksia, jotka auttavat käyttäjiä ymmärtämään, mikä meni vikaan ja kuinka korjata se. Käännä nämä virheilmoitukset eri kielille, jos mahdollista.
- Mieti saavutettavuutta: Ota huomioon vammaiset käyttäjät suunnitellessasi pakettisi käyttöliittymää ja dokumentaatiota. Noudata saavutettavuusohjeita varmistaaksesi, että pakettisi on kaikkien käytettävissä.
Edistyneet aiheet
- Nimiavaruuspaketit (Namespace packages): Mahdollistavat yhden Python-paketin jakamisen useisiin hakemistoihin tai jopa useisiin jakeluihin.
- Sisääntulopisteet (Entry points): Mahdollistavat funktioiden tai luokkien määrittelyn, joita voidaan kutsua muista paketeista tai komentoriviltä.
- Datatiedostot: Mahdollistavat muiden kuin Python-tiedostojen (esim. datatiedostot, konfiguraatiotiedostot) sisällyttämisen jakeluusi.
- Ehdolliset riippuvuudet: Mahdollistavat riippuvuuksien määrittelyn, jotka vaaditaan vain tietyissä olosuhteissa (esim. tietyssä käyttöjärjestelmässä).
Yhteenveto
Python-paketin jakelu PyPI:ssä on loistava tapa jakaa työsi maailman kanssa ja osallistua Python-ekosysteemin kehittämiseen. Noudattamalla tässä oppaassa esitettyjä vaiheita ja parhaita käytäntöjä voit luoda ja julkaista laadukkaita Python-paketteja, jotka ovat helppoja asentaa, käyttää ja ylläpitää. Muista painottaa selkeää dokumentaatiota, perusteellista testausta ja johdonmukaista versionhallintaa varmistaaksesi pakettisi menestyksen.